urbanterrorfandomcom-20200216-history
Scripting Basics
A script is a group of commands that allow you to achieve a task. Scripts can be used to: # Improve control flexibility (e.g., multiple weapon binds) # Execute multiple functions with one keystroke (e.g., demo recording) # Facilitate config customization for multiple purposes (e.g., customizing keyboard commands for playing, vs. custom commands for demo playback) Scripts are just plain text files that are saved with the .cfg file extension in your q3ut4 folder. You can execute scripts in three ways: # "On-demand" by opening Console in the game and typing the exec command. For example: /exec zoom.cfg would run a script named zoom.cfg # Automatically at game launch by adding them to a special file named autoexec.cfg. # By writing a script that executes another script. See Executables for more information. Script Organization There are many ways to organize how you script Urban Terror. Your cfg files need to be located within your game path. This location varies by operating system. Script Files By default, Urban Terror comes with three scripts. # q3config.cfg - This is your game settings file and generally should not be edited directly. # autoexec_example.cfg - Rename this to autoexec.cfg and it will be executed every time the game launches. Settings saved in autoexec.cfg will be written to q3config.cfg for you, so rather than editing q3config, edit this file instead. This can also be used to automatically execute other scripts (see Executables section). # server_example.cfg - Example server config. This helps with setting up a new game server, but we won't cover Running a server here. Scripts should be saved in a separate .cfg file from your q3config.cfg. The reason is that Urban Terror overwrites the q3config file every time you start a game or change settings and therefore will delete your scripts and comments. It is always better to make changes by adding them to autoexec.cfg or a separate .cfg file you will run manually later. For example, you may have an untouched q3config.cfg, an autoexec.cfg with all of your customized settings and key binds, and then other .cfg files for all other functions like a custom zoom script in zoom.cfg and a gear selector in gear.cfg. This is just one way to organize them. Use what's comfortable for you, but don't save your settings or scripts by editing q3config.cfg! For a really impressive example, take a look at Config: Nexu's. Script editors Before getting started, it is recommended that you use a text editor with syntax highlighting. This will help you, especially as a beginner, to understand the script and to fix errors in your code. For example, if you forget to put in a quotation mark to close off a value, a syntax highlighter will make the rest of your code all sorts of unexpected colors, tipping you off that something is wrong in the script. You don't want to waste time trying to figure out why your script doesn't work over a simple error like that! You can use any plain text editor you like, but for a list of recommended editors, see Editors for Scripts. Commenting As you write scripts, use //comments to help annotate what your script does. It will help you remember what your scripts do and why you set them up the way you did. Comments are essential if you ever plan to share your scripts with other people—we need to know what it does without reading through every line of code! Urban Terror will ignore anything that follows a pair of double-slashes (//), EXCEPT for a semicolon (;). See note below on Semicolons in comments. Semicolons in comments Be careful about semicolons (;) in comments as they will effectively end the comment, just like a new line would. For example …would output… Hello world! Hello again, world! …even though the second command came after a // comment. Basic Binds Binding a key to perform a single action is the easiest place to start. We'll start by binding the 'x' key to select the shotgun/SPAS12. The syntax is: Since we want to bind to the SPAS12, we will substitute 'x' for and 'weapon 4' for . This will give us: See List of Bindable Keys to see all possible keys you can bind. Multiple Binds We can also bind a key to execute multiple commands. Remember that Urban Terror executes commands in the order you've specified so we have to be careful. For example, we are going to bind a key to select the best choice between the SPAS12 (weapon 4) and the G36 (weapon 9). The syntax is: You have to separate the commands with a semicolon (;) so that Urban Terror recognizes where each command starts and stops. We're going to use the 'x' key again for , weapon 4 for , and weapon 9 for . This should give us: When you hit , the bind selects the first weapon (weapon 4) then immediately selects the second weapon (weapon 9). In effect, if you have both weapons in your inventory, it selects the last one in the sequence, the G36. If you only have one of the weapons, it will only find and activate that weapon. This is why we want to make sure we write weapon 4 first since given the choice between the two, we always want to end up with the G36. You can string a whole bunch of commands together to be executed all at once. For example, this bind will remove all the clutter from your screen (e.g., icons, guns, etc), take a screenshot, and then return your HUD to the way it was. Note that when using multiple commands, it is sometimes necessary to use the wait command to pause the script a moment. If your script fails to work when issuing multiple command at once, try adding a wait command. Wait will pause the script for a number of frames, not seconds. If you cap your FPS at 60, you can somewhat reliably wait for 60 frames to equal one second, but as frame rates vary, so will actual wait time. Recursive Scripts Instead of only selecting the best weapon, what if we want to toggle back and forth between two weapons like the UMP45 and the M4 or make it possible to zoom to 3x or 6x magnification? This requires a recursive script. By recursive, it means that you can cycle through the script an infinite number of times. The intent is to execute one string of commands when you hit the bound key, then re-bind the key to execute new string of commands the next time you use the key. The process is as follows Write commands for each 'step' in the script * set - tells Urban Terror that you are defining a line of commands that will be grouped and executed under the name . * - is the name of one iteration or step in your script. If you have a large number of steps, start numbering with 01. If you have 4 steps, then the highest number should be 04. For scripts with a small number of steps, you can use simple names if you like (instead of numbers), just make sure that you don't use the same name twice. * - is the command or set of commands you want to execute with the script. Multiple commands should be separated by a semicolon (;) like we learned in the Multiple Binds section. * set - this tells the script to assign to the string of commands defined in . * vstr - is the name of the next variable in the sequence to be activated. In other words, activates 01, which then set to activate 02. In your last step, make activate the first step all over again, 01.This will let your key cycle through all of the combinations you've written, then start all over from the beginning. You don't have to use a numerical sequence, but it might make it easier to keep track of. In any case, pick whatever you're comfortable with. * - Any text that follows the ut_echo command (until a quote mark or semicolon) will be shown to you as an in-game message. Useful for reminding you of what your script just did! Here's an example for a 3x - 6x zoom toggle: Set up the function This will access the two "steps," zoomtoggle01 and zoomtoggle02, that we have created in the previous example. To start, we have set the function to run the first step. When that step runs, it sets the function to run the second step instead. Bind a key to execute the function The last step is to bind a key to execute your new script. We learned the syntax in the first section, Simple Binds. The final line in the zoom toggle looks like: All this does is bind the key to execute the string of commands associated with nextzoomtoggle. Here's what it looks like when it's all put together: Try this out and play around a little. You'll be writing your own scripts in no time. Toggle Settings Any command that can be set to either "on" or "off", can be switched with a toggle. For example, you can set Always Run to either on (1) or off (0), therefore you can create a toggle that lets you switch Always Run between on or off. The syntax is: Here are a couple of examples: Look through your configuration for variables that take either a 0 or 1 value. Those are the "boolean" commands that can be set up on a toggle. Executables Using the exec command can help you to keep your autoxec.cfg clean and organized. Basically, you can create a new .cfg file, write your script there, and then add an exec command to autoexec.cfg that will run your script. Having scripts in separate files allows you to share them with teammates and just generally keep things clean. If your configuration is too large, the Quake III engine that Urban Terror runs on will have problems executing the whole thing. Separate configs set up as executables enable you to reduce the overall size of your primary autoexec. The syntax is: Here are a couple of examples that could be used in an autoexec.cfg: You can also have config files/scripts in a separate folder. For example, if you put them in a folder called "cfg" then you would use Examples Here are just a few example of scripts that can be used in your in your config. You can find more examples in the Urban Terror Wiki Script & CFG Library. Why does my script not work? There are two possible errors. One of them happens when your script is too big. All scripts should stay under 16KB in size, to solve this problem break the script or scripts into smaller files which you can then execute by adding the following lines to your autoexec.cfg (where FileName is the name of your files): If you have a lot of such sub scripts we advise you create a folder in which to store them, to keep your game directory fairly tidy. This can be done by creating a new folder with the name of your choice (we will name it "cfg" in our exemple) in your q3ut4 folder. Now place all your sub scripts into this folder, the autoexec.cfg should NOT be placed in this folder. Now add the following lines to your autoexec.cfg: Another possible error is triggered when you have too many cvar strings active (i.e too many scripts). This error is usually accompanied by an error message similar to "overflow." The only way to solve this issue is to start hacking away at what you really don't need in your scripts. Recent updates to the game (version 4.2) should limit these errors. While limitations still exist, the allowances have been greatly expanded and you are not likely to run into these problems. set, seta, sets, and setu Don't use seta, because there's an upper limit on the size of a q3config.cfg that can be read in. Just use set commands in your autoexec.cfg and, to keep it tidy, exec configs for specific stuff from within autoexec.cfg. Category:Scripts & Configs